Provider Services API

By default, the Provider Services connector searches OneKey and downloads providers (Search Before Create), and pushes field-level Data Change Requests to OneKey and writes the outcome back (DCR). Both features are built and validated against IQVIA's Optimized JSON specification across a set of contracted markets. They are a production-ready starting point, not a zero-touch product. Implementation teams can adapt the DataWeave transformation layer for country-specific OneKey data.

Use this guide only if your business requirements extend beyond standard behavior, such as adding country-specific code translations, supporting DCR comments, or adding specialty translations. Most of the effort described here is DCR-specific and lives in the OneKey System API.

Prerequisites

• Use MuleSoft Direct in Salesforce Setup only to enable, configure, deploy, and download the out-of-the-box connector. It doesn't include an editor for mapping changes. To extend the connector, download the application code from MuleSoft Direct and edit it. After you extend it, you can no longer deploy or manage the app through MuleSoft Direct; deploy and manage it in Anypoint Platform instead.
• To modify field mapping or country-specific enhancements, see the OneKey System API documentation.
• SBC and DCR require the OneKey System API to be deployed. See the Setup guide for the deployment order.

Extend Connector by Application

Both features rely on the same two applications. Keep transformation changes in the System API and orchestration changes in the Process API so each application retains one responsibility.

Separating transformation from orchestration lets you change and redeploy mappings without changing shared application flows.

Dynamic Picklist Mapping Extension

Out of the box, the Codes Job loads dynamic picklist values for these Salesforce fields:

• HealthcareProvider.ProfessionalTitle
• ProviderAffiliation.Role

To include another dynamic enum field, update the field mapping in the Codes mapping. The Codes Job uses the Salesforce Metadata API. The API has a limit of 1,000 values (active and inactive combined). To exceed this limit, manually add the values in Salesforce Object Manager using the Fields & Relationships UI.

API Modification Constraints

Mapping and configuration extension points don't make the System API and Process API contracts customizable. Preserve the following boundaries and execution order; changing them can break payload validation, record correlation, asynchronous post-processing, or DCR status transitions.

Keep the feature execution order unchanged:

1. SBC: validate the request, search or download through the System API, upsert the main provider records, add the selected result to the contract population only when it is out of contract, download relations, and then upsert related records.
2. DCR Submission: select Qualified records, enrich the Salesforce data, build the System API request, map and validate it, submit it to OneKey, and then write the Processed or Failed result to Salesforce.
3. DCR Monitoring: select Processed records, resolve and group them by country, retrieve OneKey outcomes, map the statuses, and then update parent and child DCR records.

Don't move, skip, or parallelize these stages. Later stages depend on identifiers, enriched fields, error boundaries, or statuses produced by earlier stages.

Data Change Request (DCR)

DCR extensions change the outbound Salesforce-to-OneKey validation path.

What You Can Extend

Use the following extension points in order, starting with the narrowest change that meets the requirement:

1. Update mappingTemplates/validation for field mappings, the entity allow-list, mandatory-field rules, or a country-specific override. This keeps data-contract changes in the transformation layer.
2. Update mappingTemplates/codes/codeValues.json for fields such as ACT_ROLE and IND_HCP_TITLE that use referCodesMapping. This centralizes shared code translations.
3. Update dcr.submit.schedulerFrequencyInMin, dcr.trace.schedulerFrequencyInMin, or dcr.trace.recordLimit when processing frequency or batch size must change. This adjusts job operation without changing its flow.

Within mappingTemplates, the .dwl scripts and .json files depend on each other. When you change a JSON file, check whether the matching .dwl needs the same update. Prefer keeping the existing JSON structure instead of reshaping it.

OOTB Physical Entity Scope

DCR supports six physical Salesforce entities out of the box: Account, HealthcareProvider, HealthcareProviderSpecialty, CareSpecialty, ContactPointAddress, and ProviderAffiliation.

Add another physical entity only when the customer's OneKey contract and Optimized JSON specification support that entity. Treat this as a governed connector extension:

1. Confirm the OneKey entity, operation, country, fields, and mandatory rules in the customer's contract.
2. Add the Salesforce entity to base objects.json. The entity allow-list validation always reads this file, so objects_<COUNTRY>.json can't independently enable a new entity.
3. Add the Salesforce-to-OneKey field definitions to the matching base or country-specific mapping file and add contract-backed mandatory rules to the base schema.json.
4. Add entity-specific logic to mapper.dwl only when the generic mapping path can't perform the required transformation.
5. If the new entity needs additional Salesforce data, extend only the enrichment field selection; preserve the Process API request envelope and execution order.
6. Test create and update requests, missing mandatory fields, a country outside the contracted coverage, an unsupported entity, and Submission-to-Monitoring status correlation before deployment.

Adding an entity to objects.json alone doesn't establish OneKey support and doesn't authorize a change to either API contract.

Changes We Don't Recommend

We recommend changing only the mapping templates, code-value files, and the properties listed above. The items below are part of the connector's architecture rather than extension points, and changing them can break DCR processing:

• The MuleSoft application flows, and any DataWeave outside the documented extension points. These implement the required orchestration, enrichment, Salesforce composite reads and writes, error boundaries, and status handling.
• Delete operations. DCR supports create and update only. Delete is not supported and cannot be enabled through the mapping layer.
• The entity allow-list beyond the six supported physical entities, unless the customer's OneKey contract supports the new entity and the governed extension steps above are completed.

1.1 Supporting DCR Comments

The Provider Services app already forwards populated LifeSciDataChangeRequest.Comments values to OneKey. It selects comments from the parent and child DCR records, combines the nonempty values, and the System API places the result in validation.requestComment.

If the Salesforce process that creates the DCR doesn't populate LifeSciDataChangeRequest.Comments from entity-specific comment fields, extend the DCR Handler on the Salesforce side. No Provider Services app change is required for comments that already populate this field.

How to populate the DCR comment when needed:

1. Create a custom comment field on each external DCR entity you want to carry a comment.
2. Map that custom comment field to the LifeSciDataChangeRequest.Comments field in the DCR Handler.

After LifeSciDataChangeRequest.Comments is populated, the existing integration forwards it without an additional connector mapping change.

1.2 OneKey Code Translations by Country

OneKey expects codes, while Life Sciences Cloud stores readable or picklist values. For example, HealthcareProvider.ProviderType of "Physician" must be sent to OneKey as "M" (IND_HCP_TYPE_CODE, Code "TYP"). Because these codes vary by country, define the translation per country in the mapping file.

Apply a code translation in this order so the change remains scoped to the correct field and country:

1. Identify the Salesforce source value, the OneKey target value, and the OneKey code set for the field.
2. Use an inline CodeValues block when the translation belongs only to that mapping entry; use mappingTemplates/codes/codeValues.json when the field uses referCodesMapping.

3. Add or edit the translation on the relevant entry in mapping.json. For example:

   {
       "Source_Field": "HealthcareProvider.ProviderType",
       "Target_Field": "individual.typeCode",
       "Mapping_Field": "IND_HCP_TYPE_CODE",
       "Code": "TYP",
       "CodeValues": [
           { "Source_Value": "Physician",      "Target_Value": "M" },
           { "Source_Value": "Administrators", "Target_Value": "A" },
           { "Source_Value": "Dentist",        "Target_Value": "D" }
       ]
   }

4. When the same source value maps differently by country, put the translation in the appropriate country-specific override instead of changing the base mapping for every country. See section 1.3.

1.3 Country-Specific Mapping Overrides

When you submit DCRs for more than one country from a single instance, the same generic mapping doesn't always fit every region. The System API supports per-country override files that fall back to the base file for any country without one. This is the same mechanism used by the download mappings.

mapper.dwl selects the file by the record's countryCode:

• mapping_<COUNTRY>.json → falls back to mapping.json
• objects_<COUNTRY>.json → falls back to objects.json during mapping, but doesn't extend the base entity allow-list
• codeValues_<COUNTRY>.json → falls back to codeValues.json

Create only the overrides a country needs so all other behavior continues to fall back to the base mapping:

1. Confirm the two-character ISO country code on the request, because that value selects the override.
2. Copy only the base file that needs country-specific behavior and append the country code, for example mapping_FR.json.
3. Change only the entries that differ for that country; unchanged files continue to use the base version.
4. Check whether the matching .dwl selects or transforms the changed entry, and update it only when the JSON change requires corresponding logic.
5. Test one request for the configured country and one fallback-country request to confirm the override doesn't change the base behavior.

If a region genuinely needs its own transformation logic and volume, the connector also supports running a dedicated System API instance per region, each with its own validation mapping. Treat this as an option for large or divergent regions, not a default.

1.4 Specialty Code Readability

OneKey identifies specialties by code (for example, 88, 06, 3C). DCR sends CareSpecialty.SpecialtyCode directly as IND_SP_CODE / WKP_SP_CODE, so the value you store in Salesforce must be the code OneKey expects.

Use these steps to show a readable specialty name while preserving the OneKey code required by DCR:

1. Choose where to translate the value: use a Salesforce picklist label when Salesforce can store the OneKey code, or use mapping_<COUNTRY>.json when the translation varies by country.
2. Store or map the OneKey code in CareSpecialty.SpecialtyCode; DCR sends that value as IND_SP_CODE or WKP_SP_CODE.
3. Populate and validate the specialty values for every country you submit. IND_SP_CODE is mandatory for an HCP create, so a missing translation causes validation to fail. See the Picklist Values table in the Mappings guide.

1.5 Mandatory-Field Rules

The mandatory fields OneKey requires per operation, entity type, and country are enforced by schema.json (draft-07) before the request is sent. Validating them in the connector catches a missing field early, with clear context, instead of letting OneKey reject the request downstream with less detail.

If your contract with OneKey differs from the shipped rules, apply the change in this order:

1. Confirm the requirement in the country's OneKey contract.
2. Edit the relevant operation and entity-type required array in base schema.json. The shipped schema contains US and non-US branches; the flow doesn't load schema_<COUNTRY>.json files.
3. If a contract needs a distinct rule for another country, add the country condition to base schema.json, or use a separately configured System API deployment when the regional rules are substantially different.
4. Validate both a complete request and a request missing the newly required field so the connector fails early with clear context.

We recommend retaining every rule that OneKey enforces. A request that passes the connector's schema but fails OneKey's own validation is rejected downstream with less context. Confirm the true contract with IQVIA OneKey before changing schema.json.

Out-of-the-box configuration values

These DCR-related properties and values are provided out of the box.

Search Before Create (SBC)

SBC extensions change the inbound OneKey-to-Salesforce search and download paths. Keep them separate from DCR validation mappings because the direction and runtime trigger are different.

OOTB SBC Behavior

Supported SBC Extensions

1. Update mappingTemplates/search when a search result needs a different field or transformation. This affects the synchronous result shown before a provider is selected.
2. Update mappingTemplates/download when a selected provider or related record needs a different Salesforce field mapping. This affects data written after selection.
3. Add a country-specific override beside the relevant base mapping when only one country's contract differs. Preserve the base file as the fallback for other countries.
4. Change onekey.search.resultSize when more or fewer than 20 search results are required. Values above 100 still produce an effective limit of 100 because the Mule mapping applies that cap internally.
5. Change sbc.relations.levels or sbc.workplaceHierarchy.levels only when deeper related-record traversal is required. Increasing either value increases OneKey and Salesforce API consumption, so validate performance and API usage before production deployment.
6. Verify the search response first, then download the selected provider and verify its related records. This isolates search formatting from download persistence.

For the complete SBC mapping files and extension rules, see the OneKey System API documentation.